Skip to content

feat(plugin): add ToolResult type for structured tool responses #6544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
aryasaatvik wants to merge 5 commits into
base: dev
Choose a base branch
from
Open

feat(plugin): add ToolResult type for structured tool responses #6544

aryasaatvik wants to merge 5 commits into from
+47 −15

Conversation

@aryasaatvik
Copy link
Contributor

@aryasaatvik aryasaatvik commented Dec 31, 2025 •
edited
Loading

Problem

Plugin tools could only return a plain string. This prevented:

  • Structured responses with titles, metadata, and attachments
  • Real-time streaming updates during long-running operations
  • Subagent result propagation (tool counts, progress, etc.)

Solution

Add ToolResult interface and metadata() method to plugin SDK:

  • ToolResult interface: { title, metadata, output, attachments? }
  • ctx.metadata(): Emit streaming updates during execution
  • Backward compatible: tools can still return plain strings
  • Core extraction: Tool.Result interface for unified typing

Changes

  • packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
  • packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
  • packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

Usage

import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})

Related

@aryasaatvik aryasaatvik changed the title fix: preserve plugin tool metadata on completion feat(plugin): support structured tool results with metadata Jan 1, 2026
@aryasaatvik aryasaatvik changed the title feat(plugin): support structured tool results with metadata feat(plugin): add ToolResult type for structured tool responses Jan 4, 2026
@aryasaatvik
Copy link
Contributor Author

aryasaatvik commented Jan 4, 2026

@rekram1-node can you take a look?

@github-actions github-actions bot mentioned this pull request Jan 5, 2026
Open
@aryasaatvik aryasaatvik force-pushed the fix/plugin-tool-metadata-persistence branch from 0fa0047 to d2ef4f0 Compare January 8, 2026 08:51
@github-actions
Copy link
Contributor

github-actions bot commented Jan 10, 2026

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

  1. Open an issue describing the bug/feature (if one doesn't exist)
  2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

@aryasaatvik
fix: preserve plugin tool metadata on completion
aee2429
@aryasaatvik
feat(plugin): add ToolResult type for structured tool responses
a4b2aaf 
- Add ToolResult interface to @opencode-ai/plugin
- Update execute signature to Promise<string | ToolResult>
- Enables plugin tools to return {title, metadata, output}
@aryasaatvik
fix: add type assertion for string result in fromPlugin
f316888
@aryasaatvik
feat(plugin): support structured tool results with metadata
b26525b 
- Add ToolResult interface to @opencode-ai/plugin for structured tool responses
- Update execute signature to accept string | ToolResult
- Add runtime detection in fromPlugin to preserve title and metadata
- Extract Tool.Result interface for clarity in opencode package
- Maintain backward compatibility with string-only results
@aryasaatvik
feat(plugin): add metadata method to ToolContext for enhanced tool fu…
f35c3da 
…nctionality
@aryasaatvik aryasaatvik force-pushed the fix/plugin-tool-metadata-persistence branch from c0c0acf to f35c3da Compare January 10, 2026 06:53
@aryasaatvik aryasaatvik mentioned this pull request Jan 10, 2026
Open
aryasaatvik added a commit to aryasaatvik/opencode that referenced this pull request Jan 12, 2026
@aryasaatvik
feat(plugin): add ToolResult type for structured tool responses
23c099d 
## Problem

Plugin tools could only return a plain string. This prevented:
- Structured responses with titles, metadata, and attachments
- Real-time streaming updates during long-running operations
- Subagent result propagation (tool counts, progress, etc.)

## Solution

Add ToolResult interface and metadata() method to plugin SDK:

- ToolResult interface: { title, metadata, output, attachments? }
- ctx.metadata(): Emit streaming updates during execution
- Backward compatible: tools can still return plain strings
- Core extraction: Tool.Result interface for unified typing

## Changes

- packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
- packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
- packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

## Usage

```typescript
import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})
```

## Related

- Resolves anomalyco#7590

Patchwork-Source: fix/plugin-tool-metadata-persistence
Patchwork-PR: anomalyco#6544
Patchwork-Squashed: 2026-01-12T21:07:21.648Z
aryasaatvik added a commit to aryasaatvik/opencode that referenced this pull request Jan 12, 2026
@aryasaatvik
feat(plugin): add ToolResult type for structured tool responses
cc38845 
## Problem

Plugin tools could only return a plain string. This prevented:
- Structured responses with titles, metadata, and attachments
- Real-time streaming updates during long-running operations
- Subagent result propagation (tool counts, progress, etc.)

## Solution

Add ToolResult interface and metadata() method to plugin SDK:

- ToolResult interface: { title, metadata, output, attachments? }
- ctx.metadata(): Emit streaming updates during execution
- Backward compatible: tools can still return plain strings
- Core extraction: Tool.Result interface for unified typing

## Changes

- packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
- packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
- packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

## Usage

```typescript
import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})
```

## Related

- Resolves anomalyco#7590

Patchwork-Source: fix/plugin-tool-metadata-persistence
Patchwork-PR: anomalyco#6544
Patchwork-Squashed: 2026-01-12T21:07:21.648Z
aryasaatvik added a commit to aryasaatvik/opencode that referenced this pull request Jan 12, 2026
@aryasaatvik
feat(plugin): add ToolResult type for structured tool responses
0bb1508 
## Problem

Plugin tools could only return a plain string. This prevented:
- Structured responses with titles, metadata, and attachments
- Real-time streaming updates during long-running operations
- Subagent result propagation (tool counts, progress, etc.)

## Solution

Add ToolResult interface and metadata() method to plugin SDK:

- ToolResult interface: { title, metadata, output, attachments? }
- ctx.metadata(): Emit streaming updates during execution
- Backward compatible: tools can still return plain strings
- Core extraction: Tool.Result interface for unified typing

## Changes

- packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
- packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
- packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

## Usage

```typescript
import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})
```

## Related

- Resolves anomalyco#7590

Patchwork-Source: fix/plugin-tool-metadata-persistence
Patchwork-PR: anomalyco#6544
Patchwork-Squashed: 2026-01-12T21:07:21.648Z
aryasaatvik added a commit to aryasaatvik/opencode that referenced this pull request Jan 13, 2026
@aryasaatvik
feat(plugin): add ToolResult type for structured tool responses
9f731ba 
## Problem

Plugin tools could only return a plain string. This prevented:
- Structured responses with titles, metadata, and attachments
- Real-time streaming updates during long-running operations
- Subagent result propagation (tool counts, progress, etc.)

## Solution

Add ToolResult interface and metadata() method to plugin SDK:

- ToolResult interface: { title, metadata, output, attachments? }
- ctx.metadata(): Emit streaming updates during execution
- Backward compatible: tools can still return plain strings
- Core extraction: Tool.Result interface for unified typing

## Changes

- packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
- packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
- packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

## Usage

```typescript
import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})
```

## Related

- Resolves anomalyco#7590

Patchwork-Source: fix/plugin-tool-metadata-persistence
Patchwork-PR: anomalyco#6544
Patchwork-Squashed: 2026-01-12T21:07:21.648Z
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@adamdotdevin adamdotdevin Awaiting requested review from adamdotdevin

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat(plugin): add ToolResult type for structured tool responses

1 participant

@aryasaatvik